home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
ShareWare OnLine 2
/
ShareWare OnLine Volume 2 (CMS Software)(1993).iso
/
prog
/
ibrary10.zip
/
IBRARY.DOC
< prev
next >
Wrap
Text File
|
1993-04-23
|
26KB
|
735 lines
IBRARY: An ASIC Library
=-------------------------=
Version 1.0
IBRARY Copyright (c) 1993 Thomas G. Hanlin III
This is IBRARY, a library of over 135 routines written in
assembly language for use with David A. Visti's ASIC compiler.
You will need ASIC 4.0 or later and a linker to use IBRARY. An
assembler is not necessary. The IBRARY collection is
copyrighted and may be distributed only under the following
conditions:
All IBRARY files must be distributed together as a unit.
No files may be altered, added, or deleted from this unit.
YOU USE THIS LIBRARY AT YOUR OWN RISK. I have tested it on my
own computer, but I will not assume any responsibility for any
problems which IBRARY may cause you. If you do run into a
problem, please let me know about it, and I will do my best to
verify and repair it.
It is expected that if you find IBRARY useful, you will
register your copy. You may not use IBRARY routines in
programs intended for sale unless you have registered.
Registration gets you the latest version of IBRARY, complete
with full source code. The assembly language code is designed
for MASM 6.0 and may require alteration for other assemblers.
See the ORDER.FRM file for ordering information.
Warning: Unregistered use of IBRARY for more than 30 days may
cause the author to practice yodeling outside your bedroom
window at night. Don't let this happen to you!
Table of Contents page 2
Synopsis and Legal Info .................................... 1
Table of Contents .......................................... 2
Overview ................................................... 3
Equipment Info ............................................. 4
Extended Math .............................................. 8
Graphics ................................................... 9
Interrupts ................................................ 12
Joystick Support .......................................... 13
Mouse Support ............................................. 14
Miscellaneous ............................................. 17
Overview page 3
As of version 4.0, ASIC became a much more powerful language,
with the introduction of library support. A library is very
like an extension to a compiler. It provides capabilities
which are perhaps insufficiently general-purpose to add into
the language itself, but which may nonetheless be of use to
many people. Libraries let you customize a language to suit
your particular needs.
The routines in IBRARY are contained in a library file, which
is denoted by the extension .LIB. So, the IBRARY library is
named IBRARY.LIB. How you access this library depends on which
version of the compiler you use: ASIC.EXE or ASICC.EXE.
In the case of ASICC.EXE, the command to compile a program
which uses IBRARY looks something like this:
ASICC progname B/OBJ LIB=IBRARY LNK=C:\DOS
Here, "progname" is the name of the program to compile. When
you use a library, compilation turns into a multi-part process.
ASIC first turns your .ASI code into an .OBJ file. It then
calls your LINK.EXE program to combine the .OBJ file with the
routines you need from IBRARY.LIB, turning the result into an
.EXE program. In the above command line, the LNK=C:\DOS part
tells ASIC that it can find LINK.EXE in a directory called
C:\DOS. You will need to use the appropriate directory for
your computer. Note that LINK.EXE does not come with ASIC. It
is provided with Microsoft languages and many DOS versions,
though. Borland also has a linker, called TLINK.EXE.
IBRARY includes a batch file, ASICMAKE.BAT, to make all this
easier. You will need to modify it to have the appropriate
LNK= setting, but once that's done, you can simply type:
ASICMAKE progname
...in order to compile and link your program.
In the case of the editor/environment, the initial setup is a
bit different. From the Compiler menu, pick Advanced Options.
From the Advanced Options menu, do the following:
choose .OBJ output file generation
set library name to IBRARY
set link path to wherever your LINK.EXE is (e.g., C:\DOS)
It's as easy as that! You are now set up to use libraries. A
good first test would be to compile the IBRARY quick demo,
subtly entitled DEMO.ASI. Give it a try!
Equipment Info page 4
The equipment routines give you information about the computing
environment. This includes both installed software and hardware.
The first function allows you to determine if an "enhanced"
keyboard (101-key) is installed. It may not be able to figure
out what the keyboard is on some older not-quite-clone PCs, in
which case it will take the safe way out and report that there
is no enhanced keyboard. This routine returns -1 if there is
an enhanced keyboard present, 0 if not.
CALL SUB "KbdType" Enhanced
Want to know the type of processor (CPU) being used? Can do!
CALL SUB "Processor" CPUType
The results will be returned as a number which can be decoded
as follows:
0 NEC V20
1 8088 or 8086
2 80186
3 80286
4 80386
5 80486
Maybe you'd like to check for a CD-ROM drive:
CALL SUB "CDROM" Drives
This tells you how many logical drives exist, if there is a
CD-ROM available. If not, it will return 0. Note that the
CD-ROM installation check conflicts with the GRAPHICS.COM
installation check for DOS 4.0, due to some screw-up at IBM or
Microsoft.
The number of floppy drives installed is retrieved like this:
CALL SUB "Floppies" Drives
Equipment Info page 5
There may be up to four floppy drives in a system; however, the
AT CMOS data area only directly supports two. This makes it
easy to find out what kind of drives the first two are, but not
the second two. Oh well, guess we'll have to settle for what
we can get, right?
CALL SUB "FloppyType" Drive1 Drive2
The results from FloppyType are returned as follows:
0 no drive
1 5 1/4" 360K
2 5 1/4" 1.2M
3 3 1/2" 720K
4 3 1/2" 1.44M
Result codes of 5-7 are available, but not yet defined. One
might guess that the 2.88M drive supported by DOS 5.0 will be
drive type 5. Has anybody seen one of those puppies yet?
New memory types sure have burgeoned over the years...
expanded, extended, and now XMS. There are routines to check
all of these:
REM get total extended memory installed
CALL SUB "AllExtMem" AllExt&
REM get BIOS extended memory installed
CALL SUB "GetExtM" BiosExt&
REM get expanded (EMS) memory installed
CALL SUB "GetEMSm" TotalPages FreePages
REM get XMS memory installed
CALL SUB "GetXMSm" BigFree& TotalFree&
When you're dealing with extended memory, whether it be
BIOS-type or using the XMS standard, the results are returned
in kilobytes. Multiply 'em by 1024 to convert to bytes. When
you're dealing with expanded memory (EMS), the results are in
pages of 16,384 bytes.
I might note, by the way, that Microsoft seems to have
intentionally crippled the XMS standard. It can only support a
maximum of 64 megabytes. This may seem like a lot now, but
it'll seem cramped soon enough.
A few more routines to get the versions of EMS and XMS, if any:
CALL SUB "GetEMSv" MajorV MinorV
CALL SUB "GetXMSv" MajorV MinorV
These return the major and minor version numbers as two
separate integers. For example, EMS 4.0 would return major
version 4, minor version 0.
Equipment Info page 6
It's nice to know a little about the operating environment.
With the below routines, you can find out what the DOS version
is; what version of 4DOS, if any, is in use; and whether
Microsoft Windows is running.
CALL SUB "GetDOSv" MajorV MinorV
CALL SUB "Get4DOSv" MajorV MinorV
CALL SUB "WinCheck" MajorV MinorV
These return results as major and minor version numbers, as
discussed on the previous page. The Get4DOSv and WinCheck
routines return zeroes if 4DOS and Windows, respectively, are
not available.
There are a couple of curious features of GetDOSv to keep in
mind. If the version is 10 or higher, you're running in OS/2
compatibility mode. DOS version 10 is actually OS/2 1.0,
version 20 is OS/2 2.0, and so on. Secondly, if you're using
DOS 5.0, the version reported may not be 5.0-- DOS 5.0 can be
told to reply with a lower version number to allow some older
software (which checks for a specific DOS version) to run
properly.
One final routine that should be of some value is the one that
allows you to find out what kind of display is available. It
tells you the specific adapter and whether the display is color
or monochrome. There is one case in which it can be confused,
however-- if the adapter is CGA, the display is assumed to be
color, since there is no way for the computer to know any
differently. So, although this routine provides a good idea of
what is available, it would be a good idea to provide an option
to tell the program that a monochrome display is attached.
Microsoft normally uses "/B" for this purpose, so that might be
a good standard to stick with.
CALL SUB "GetDisplay" Adapter Mono
This returns Mono = -1 for a monochrome display, or Mono = 0
for a color display. The Adapter may be any of the following:
1 MDA
2 Hercules
3 CGA
4 EGA
5 MCGA
6 VGA
Equipment Info page 7
Aside from some of the oldest semi-clones, it's possible to
find out what sort of machine you're using by looking at a
specific data byte. You can access this as follows:
CALL SUB "PCType" PcType
The result will need decoding. Here are some known values:
255 PC or XT
254 XT
253 PCjr
252 PC AT
251 XT
250 PS/2 Model 30
249 PC Convertible
248 PS/2 Model 70 or 80
154 Compaq Portable
45 Compaq Portable
Likewise, all but some of the oldest semi-clones maintain a
BIOS date value which tells you how old the BIOS ROM is. This
can be retrieved with the following routine:
CALL SUB "PCDate" PCDate$
If your program is running on one of the rare old machines
which don't maintain a valid BIOS date, this routine will
return "No Date " instead of an actual date.
As far as a program is concerned, DR DOS is essentially the
same as MS-DOS. Still, it's always nice to know what sort of
operating environment you have. You can find out whether your
program is running under DR DOS with the following function:
CALL SUB "DrDos" DrDos
IF DRDOS = 0 THEN
PRINT "MS-DOS"
ELSE
PRINT "DR DOS"
ENDIF
The number of serial and parallel ports available can be
readily obtained:
CALL SUB "CommPorts" CommPorts
CALL SUB "PrtPorts" PrtPorts
Extended Math page 8
The extended math routines provide a number of simple binary
functions which operate on an integer as a stream of bits. You
may shift or rotate the bits in an integer by an arbitrary
amount in either direction.
Note that the normal ASIC integer has a length of 16 bits.
CALL SUB "LShift" Number ShiftCount
CALL SUB "RShift" Number ShiftCount
CALL SUB "LRotate" Number ShiftCount
CALL SUB "RRotate" Number ShiftCount
An identical set of routines is provided for long integers,
which have a length of 32 bits.
CALL SUB "LShiftL" Number& ShiftCount
CALL SUB "RShiftL" Number& ShiftCount
CALL SUB "LRotateL" Number& ShiftCount
CALL SUB "RRotateL" Number& ShiftCount
Graphics Support page 9
Much of the design of ASIC appears to be oriented on the notion
of creating the smallest possible programs. In that respect,
it is perhaps not surprising that ASIC doesn't include strong
graphics support. IBRARY provides support for EGA and VGA
modes which ASIC doesn't. A future version of IBRARY will
include advanced support for many more video modes.
Mode Description
==== ================================================
8 640x200, 16 colors, 80x25 text, EGA or better
11 640x480, 2 colors, 80x25 text, VGA or better
12 640x480, 16 colors, 80x25 text, VGA or better
13 320x200, 256 colors, 40x25 text, VGA or better
N0 360x480, 256 colors, 45x60 text, VGA or better
N1 320x400, 256 colors, 40x25 text, VGA or better
The graphics routines all use the same nomenclature: a G,
followed by a mode number, followed by the specific name. This
generic naming convention is used so that this chapter can
refer to all available modes. For example, if I say "G#Color"
and you're using mode 12, you'd actually use "G12Color" in your
program. Ok?
You just use G#Mode with a non-zero value to enter graphics
mode, or zero to restore text mode. The text mode is assumed
to be the normal 80x25 color mode. If this would not be your
choice, you can safely use the ASIC SCREEN statement to pick a
mode that's more to your liking.
Here's an example for typical handling of one of the non-SVGA
modes (in this case, mode 12):
CALL SUB "G12Mode" 1
REM *** your main program goes here ***
CALL SUB "G12Mode" 0
Graphics Support page 10
One difference between ASIC and IBRARY is that, instead of
each "draw" command requiring a color parameter as in ASIC,
IBRARY provides a separate color command:
CALL SUB "G#Color" Foreground Background
The foreground color is used by all graphics routines. The
background color is used by the G#Cls routine. Both foreground
and background colors are used in by G#Write and G#WriteLn.
Here is a list of the corresponding routines, first ASIC, then
IBRARY (replace the "#" with the appropriate mode number):
REM get the color of a specified point
colour = POINT(x, y)
CALL SUB "G#GetPel" x y colour
REM set the color of a specified point
PSET (x, y), colour
CALL SUB "G#Color" colour, backgnd
CALL SUB "G#Plot" x y
REM clear the screen and home the cursor (if any)
CLS
CALL SUB "G#Cls"
REM get the current cursor position
Row = CSRLIN
Column = POS(0)
CALL SUB "G#GetLocate" Row Column
REM set the current cursor position
LOCATE Row, Column
CALL SUB "G#Locate" Row Column
REM display a string without a carriage return and linefeed
PRINT St$;
CALL SUB "G#Write" St$
REM display a string with a carriage return and linefeed
PRINT St$
CALL SUB "G#WriteLn" St$
If you need to print a number rather than a string, just use
the BASIC function STR$ to convert it. If you don't want a
leading space, you can use the IBRARY routine, StrNB:
CALL SUB "StrNB" Number St$
Graphics Support page 11
The IBRARY library has other graphics routines which have no
ASIC equivalent. Here's a list:
REM get the current colors
CALL SUB "G#GetColor" Foreground Background
REM draw a line
CALL SUB "G#Line" x1 y1 x2 y2
REM draw a box (set filled = 0 for frame, = 1 to fill it)
CALL SUB "G#Box" x1 y1 x2 y2 filled
REM get a VGA palette value
CALL SUB "GetPalRGB" Colour RedI GreenI BlueI
REM set a VGA palette value
CALL SUB "SetPalRGB" Colour RedI GreenI BlueI
The most obvious aspect of palettes is in the ability to select
a set of colors suited to a specific application. When showing
a picture of the sea, you might want mostly blues and greens,
for instance. There are other implications in the ability to
quickly change a color across the entire screen, however. It
allows for simple animation, the ability to fade in or fade
out, and other interesting effects. Let your imagination run
loose and experiment a little! You'll be surprised by the
power of palette manipulation.
Interrupts page 12
The interrupt routines give you access to some of the more
common BIOS and DOS interrupts, with a couple of convenience
features thrown in for good measure.
NOTE that these routines access the computer at a very low
level. If you don't know what you're doing or make a mistake,
you could cause serious trouble. Be warned!
Three routines are provided for accessing common interrupts.
They allow you to set the AX, BX, CX, and DX registers, and
return the new values of the same, plus the flags.
REM access to INT 21h, the DOS function handler
CALL SUB "DosInt" AX BX CX DX Flags
REM access to INT 10h, the BIOS video handler
CALL SUB "VidInt" AX BX CX DX Flags
REM access to INT 16h, the BIOS keyboard handler
CALL SUB "KbdInt" AX BX CX DX Flags
Each of the 16-bit registers AX, BX, CX and DX can be divided
in half and accessed as 8-bit values: AH, AL, BH, BL, and so
on. To make it easier to work with the registers as either
8-bit or 16-bit quantities, IBRARY includes routines to split a
16-bit word into two 8-bit bytes, and vice versa:
CALL SUB "SplitWord" Word HiByte LoByte
CALL SUB "JoinBytes" HiByte LoByte Word
The Flags value is a set of bit flags indicating the value of
the processor's flag register. Bit 0 contains the carry flag
and bit 6 contains the zero flag. There are a few other flags
involved, but you should never need to access them.
Joystick Support page 13
The joystick routines allow you to read the positions and
buttons of up to two joysticks. If only one joystick is
attached, the results for the second joystick will usually be
meaningless. In the case of the FlightStick joystick, if only
one joystick is attached, the value for the Y position of the
second joystick will indicate the FlightStick throttle setting.
The joysticks are labeled "A" and "B" for these routines, where
"A" is the first joystick.
You can read the joystick buttons individually or all at once.
If speed is an issue, you should read the buttons all at once,
as this is considerably faster than reading them one at a time
(assuming you wish to read more than one button).
CALL SUB "JButtonA1" Pressed
CALL SUB "JButtonA2" Pressed
CALL SUB "JButtonB1" Pressed
CALL SUB "JButtonB2" Pressed
CALL SUB "JButtons" A1Pressed A2Pressed B1Pressed B2Pressed
The value returned will be -1 if the button is pressed or 0 if
it is not pressed.
You can also get the position of the joysticks. This is
returned as a pair of X,Y coordinates for each joystick. The
starting and ending positions depend on the individual
joystick, game adapter, and computer, so your program must
calibrate itself to the individual joystick. I find a range of
about 5-140 on my FlightStick; your mileage may vary.
CALL SUB "JPos" AX AY BX BY
Note that the joystick routines are BIOS-dependent. They will
not work on some of the oldest PCs (those made before 1983 or
thereabouts).
Mouse Support page 14
The mouse routines provide full-featured mouse support. You
can see if a mouse is available and how many buttons it has,
get the cursor position (either the current position or the
position at the last press or release of a specified button),
set the cursor position, change the cursor, set the mouse
range, get hardware information about the mouse, and so on.
There are two unusual mouse modes to be aware of. One is text
mode, which is mapped to a 640x200 virtual display. So, to
convert the results to text format, you need to divide the
cursor position by eight and add one. To convert from text
format, subtract one and multiply by eight.
The second unusual mode is 320x200 CGA mode, which is also
mapped to 640x200. To convert the coordinates to this mode,
divide X by two. To convert from this mode, multiply the X
coordinate by two.
All other modes use the actual display coordinates instead of a
bizarro virtual screen. Why the peculiar CGA and text modes?
Well, evidently Microsoft never thought there'd be any video
adapters besides MDA and CGA, and decided to create a single
virtual screen size that worked for all modes. Not a bad idea,
I guess, but rather shortsighted. Oh well.
One other nuisance that you may run into is that the mouse
cursor can't be directly turned on or off. A "cursor
visibility" count is maintained-- if the mouse cursor was
turned on twice, you'll need to turn it off twice before it
will actually disappear.
Before using the mouse, you must initialize it. The
initialization routine also checks to make sure that a mouse is
installed and tells you how many buttons it has. It's best to
initialize the mouse after setting the screen mode, so the
mouse driver understands what mode you're using. Not all mouse
drivers support all screen modes, but you can reasonably expect
any current mouse driver to support MDA, CGA, EGA, and VGA.
Hercules graphics mode is rarely supported, as it must be set
through direct hardware access rather than the standard
techniques, so the mouse driver has little way of knowing that
you've changed the mode.
The mouse routines will work equally well with two-button or
three-button rodents. The middle button functions will return
0 with two-button mice.
Mouse Support page 15
I won't go into great detail on these routines, because they're
pretty much self-explanatory. The mouse is a fairly easy
device to deal with, despite the quirks of Microsoft's driver.
You can initialize the mouse driver like so:
CALL SUB "MInit" Buttons
This returns the number of mouse buttons available. If there
is no mouse, zero will be returned. Initialize the mouse AFTER
setting the screen mode, so it knows what the screen is like.
You can make the mouse cursor visible or invisible. It will
function just as well in either state. See the previous page
for some quirks.
CALL SUB "MShow"
CALL SUB "MHide"
There are many ways to get the mouse cursor position. You can
get the current position, the position at which the mouse was
located when a particular button was pressed, or the position
when a button was released. If you choose a past position, you
can also find out how many presses or releases of the button
have taken place since you last checked.
REM current coordinates
CALL SUB "MWhereX" X
CALL SUB "MWhereY" Y
REM number of presses of a given button
REM and mouse position at last press
CALL SUB "MLClick" Count X Y
CALL SUB "MMClick" Count X Y
CALL SUB "MRClick" Count X Y
REM number of releases of a given button
REM and mouse position at last release
CALL SUB "MLRelease" Count X Y
CALL SUB "MMRelease" Count X Y
CALL SUB "MRRelease" Count X Y
Mouse Support page 16
If you'd prefer to find out which buttons are currently
pressed, no problem:
CALL SUB "MLButton" IsDown
CALL SUB "MMButton" IsDown
CALL SUB "MRButton" IsDown
Of course, you can also set the cursor location:
CALL SUB "MLocate" X Y
The mouse cursor range can be restricted to a given area of the
screen. This area is expressed by giving the upper left corner
and lower right corner of the rectangular area to which to
restrict the cursor.
CALL SUB "MWindow" X1 Y1 X2 Y2
There are a variety of cursor shapes available for graphics
mode:
0 hourglass ("please wait, program is working" symbol)
1 pointing arrow (default)
2 pointing hand
3 crosshair
4 target (box in a box)
5 grabbing hand
If you have ideas for more, let me know and I'll see what I can
do. Cursor shapes are not unduly difficult to define, although
it's technical enough so that I decided to avoid confusion by
leaving direct handling out of IBRARY.
CALL SUB "MCursorG" CursorNr
Miscellaneous page 17
If there are not (yet) enough routines in a category to give
them their own classification, they come to roost here, in good
ol' Miscellaneous. At the moment, this consists of a string
routine and some DOS output routines.
The StrNB routine works like ASIC's built-in STR$ function, but
strips all leading blanks from the result. It works on plain
integers.
CALL SUB "StrNB" Number Result$
The DOS output routines allow you to send output to the default
DOS device-- normally the screen, although it can be redirected
by the user to another device or to a file. We start with a
generic PRINT replacement:
CALL SUB "DosPrint" St$
That sends a string to standard output. If you want a carriage
return and linefeed, you must add them yourself:
CrLf$ = CHR$(13) + CHR$(10)
St$ = St$ + CrLf$
The rest of the DOS output routines require ANSI.SYS or another
ANSI driver to be loaded. They send the appropriate ANSI codes
to standard output.
CALL SUB "DosCls"
CALL SUB "DosColor" Foreground Background
CALL SUB "DosLocate" Row Column